API Model for Messenger Service

In the previous lesson, we decided on the architectural aspects of designing the Messenger API’s communication protocols and data formats. In this lesson, we will describe the endpoints, data entities, and the message format required for a chat between clients.

Base URL and API endpoints#

We will use the following URL for designing the Messenger API. The api.messenger.com is the host URL followed by the version v1.0 and the service.

The following illustration represents the operations and their associated endpoints:

Let's go over the purpose of the endpoints below:

• WebSocket connection: This endpoint is used to establish a WebSocket connection with a chat server.

• Retrieve or upload an asset: This endpoint is accessed to retrieve or upload a media file.

• Retrieve a paginated list of messages: These endpoints are targeted to retrieve a paginated list of messages.

Remember: We don't have an endpoint for a live and offline chat because we use WebSockets for such communication. We will shortly see how that interaction between users takes place.

The message format for API endpoints#

In this section, we’ll discuss data entities, requests, and response structures for each functional requirement. We will also look at how a WebSocket connection is established to send one-to-one messages. Let's start our discussion with data entities.

Message data entities#

Following are the key data entities that are exchanged between the client and server:

Establishing WebSocket connection#

Before sending a message, it is mandatory to have a WebSocket connection established with the chat server. Therefore, we must establish a connection with the chat server represented by the v1.0/chat endpoint. As shown below, the encoding parameter encoding=text shows that the messages will be exchanged in the UTF-8 encoding after the successful connection.

• HTTP method: The WebSocket connection with the chat server is established by simply sending an HTTP GET request with some essential headers.

• Request format: In the request body, we set the value of the Connection header to Upgrade and the value of the Upgrade header to websocket, indicating that we want to upgrade our current HTTP connection to the WebSocket protocol. The request is shown in the following code widget:

• Response format: When the connection is successfully established, the server returns a response, as shown below. In the response, we see the status code 101, indicating that the WebSocket protocol has been successfully upgraded.

The following figure illustrates the process of WebSocket connection establishment:

In the above figure, we establish an HTTP connection with the chat server, which is then upgraded to a WebSocket connection.

Note: As soon as a WebSocket connection is established between a client and chat server, the latter communicates about the connection to the WebSocket manager, which updates its mapping table.

Live communication#

After establishing a WebSocket connection, let's see how text messages are sent over this connection in the JSON format. Before sending the data over the connection, the WebSocket API converts it to the UTF-8 encoded text format. Let's start with a message without an attachment.

Message without an attachment#

When the clients establish the WebSocket connection with the server, they can send and receive text messages to each other. A sample text message, along with its metadata, is shown below:

When the server receives the message, it will send an acknowledgment back to the sender showing that it has received it. Line 9 in the following code widget shows that the attribute receivedServer is set to true in the response from the server. Similarly, the server responds with the delivered and read attributes as true when the receiver receives and reads the message.

Retrieving offline messages#

When the presence server determines that some user's status is offline, the messages intended for them are stored in the database and marked undelivered. When a user comes online, the presence server receives a heartbeat event from them, the chat server is notified, and the WebSocket connection is established. In the next step, the messages are delivered via the WebSocket connection in the format shown below:

Note: he WebSocket protocol uses some control signals, such as ping and pong, that work as the heartbeat to check that the client is still responsive.

Retrieving a paginated list of messages on alternative devices#

While messages may be retrieved locally from a database, they are not readily available on alternative devices. In that case, the client may GET messages in the form of a paginated list. Let's discuss the request and response size for retrieving a paginated list of messages on other devices.

Note: We have a detailed lesson on the different types of pagination. You can revisit it here.

• HTTP method: To retrieve a paginated list of messages, we use the GET method.

• Request format: In the query string, we mentioned the userID representing the sender's window, from whom the messages are retrieved. The query string contains the after_id and limit, which shows the message ID and the number of messages we want to receive, respectively.

• Response format: The response from the server contains a list of messages in the body, as shown below:

To retrieve a paginated list of messages, the body in each response consists of messages along with the message metadata, such as senderId, receiverId, messageId, timestamp, and so on.

Remember: We will use this endpoint only to retrieve a paginated list of messages. To perform real-time chatting via the alternative device, a WebSocket connection will still be required to establish two-way communication with the server.

Failed requests#

The following table indicates different status codes in case of errors while performing various operations relevant to sending or receiving messages:

Summary#

A summary of the request detail for each endpoint is shown in the table below. The two-way chat is performed via WebSocket protocol, and the rest of the operations are performed via HTTP methods.